home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3s / fclose.z / fclose
Encoding:
Text File  |  2002-10-03  |  6.5 KB  |  133 lines
  1.  
  2.  
  3.  
  4. ffffcccclllloooosssseeee((((3333SSSS))))                                                          ffffcccclllloooosssseeee((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _ffff_cccc_llll_oooo_ssss_eeee, _ffff_ffff_llll_uuuu_ssss_hhhh - close or flush a stream
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_tttt_dddd_iiii_oooo_...._hhhh_>>>>
  13.  
  14.      _iiii_nnnn_tttt _ffff_cccc_llll_oooo_ssss_eeee _((((_FFFF_IIII_LLLL_EEEE _****_s_t_r_e_a_m_))))_;;;;
  15.  
  16.      _iiii_nnnn_tttt _ffff_ffff_llll_uuuu_ssss_hhhh _((((_FFFF_IIII_LLLL_EEEE _****_s_t_r_e_a_m_))))_;;;;
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      _ffff_cccc_llll_oooo_ssss_eeee causes any buffered data waiting to be written for the named
  20.      _s_t_r_e_a_m [see _iiii_nnnn_tttt_rrrr_oooo(3)] to be written out, and the _s_t_r_e_a_m to be closed.  If
  21.      the underlying file pointer is not already at end of file, and the file
  22.      is one capable of seeking, the file pointer is adjusted so that the next
  23.      operation on the open file pointer deals with the byte after the last one
  24.      read from or written to the file being closed.
  25.  
  26.      If _s_t_r_e_a_m points to an output stream or an update stream on which the
  27.      most recent operation was not input, _ffff_ffff_llll_uuuu_ssss_hhhh causes any buffered data
  28.      waiting to be written for the named _s_t_r_e_a_m to be written to that file.
  29.      Any unread data buffered in _s_t_r_e_a_m is discarded.  The _s_t_r_e_a_m remains
  30.      open.
  31.  
  32.      When calling _ffff_ffff_llll_uuuu_ssss_hhhh, if _s_t_r_e_a_m is a null pointer, all files open for
  33.      writing only and all files open for update whose last operation was a
  34.      write are flushed.
  35.  
  36.      _ffff_ffff_llll_uuuu_ssss_hhhh(_NNNN_UUUU_LLLL_LLLL) is performed automatically on calling _eeee_xxxx_iiii_tttt.
  37.  
  38. NNNNOOOOTTTTEEEESSSS
  39.      If two _s_t_r_e_a_m_s point to the same underlying file descriptor, the
  40.      semantics associated with their use is complex.  They are described in
  41.      detail in the _P_O_S_I_X_9_0 _1_0_0_3._1 _s_e_c_t_i_o_n _8._2._3.  The most common way for an
  42.      unsuspecting application writer to wander into this situation is via
  43.      _ffff_oooo_rrrr_kkkk(2).  _ffff_oooo_rrrr_kkkk of course replicates the process, including any stdio
  44.      buffers, while both the parent's and child's underlying file descriptor
  45.      share a common file offset pointer.  This means that actions performed in
  46.      one process may affect the other.  Consider the following:
  47.  
  48.                Parent:
  49.                     fp = fopen("foo", "r");
  50.                     fread(buf, 100, 1, fp);
  51.                     fork();
  52.                     wait(NULL);
  53.                     fread(buf, BUFSIZ+1, 1, fp);
  54.                Child:
  55.                     fclose(fp);
  56.                     exit(0);
  57.  
  58.      The parent reads the first 100 bytes which really reads _BBBB_UUUU_FFFF_SSSS_IIII_ZZZZ bytes into
  59.      an internal _s_t_r_e_a_m buffer.  The underlying file descriptor has its file
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ffffcccclllloooosssseeee((((3333SSSS))))                                                          ffffcccclllloooosssseeee((((3333SSSS))))
  71.  
  72.  
  73.  
  74.      offset set to _BBBB_UUUU_FFFF_SSSS_IIII_ZZZZ.  After the _ffff_oooo_rrrr_kkkk, the parent waits for the child.
  75.      The child calls _ffff_cccc_llll_oooo_ssss_eeee which causes the underlying file descriptor to be
  76.      synchronized with _s_t_r_e_a_m.  In this case that means that an _llll_ssss_eeee_eeee_kkkk on the
  77.      underlying file descriptor will be performed to set the file offset back
  78.      to 100.  Since the file descriptor offset pointer is shared between
  79.      parent and child, the parent's file descriptor now points at offset 100.
  80.      When the parent continues reading and finishes the first buffer, a second
  81.      buffer will be read.  The parent is assuming that the file offset is
  82.      still at _BBBB_UUUU_FFFF_SSSS_IIII_ZZZZ but the child's actions have changed it to 100.  The
  83.      parent will get the incorrect data.  The solution to this to either not
  84.      have the child call _ffff_cccc_llll_oooo_ssss_eeee or to synchronize the file descriptor with
  85.      _s_t_r_e_a_m before calling _ffff_oooo_rrrr_kkkk.  Synchronization is done by calling
  86.      _ffff_ffff_llll_uuuu_ssss_hhhh(_f_p).  Note that calling _ffff_ffff_llll_uuuu_ssss_hhhh(_NNNN_UUUU_LLLL_LLLL) will not suffice since it
  87.      doesn't effect read only streams.
  88.  
  89. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  90.      _cccc_llll_oooo_ssss_eeee(2), _eeee_xxxx_iiii_tttt(2), _iiii_nnnn_tttt_rrrr_oooo(3), _ffff_oooo_pppp_eeee_nnnn(3S), _ssss_eeee_tttt_bbbb_uuuu_ffff(3S), _ssss_tttt_dddd_iiii_oooo(3S)
  91.  
  92. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  93.      On successful completion these functions return a value of zero.
  94.      Otherwise _EEEE_OOOO_FFFF is returned.  For _ffff_ffff_llll_uuuu_ssss_hhhh(_NNNN_UUUU_LLLL_LLLL), an error is returned if any
  95.      files encounter an error.  For _ffff_cccc_llll_oooo_ssss_eeee, _EEEE_OOOO_FFFF is returned if _s_t_r_e_a_m is _NNNN_UUUU_LLLL_LLLL,
  96.      or _s_t_r_e_a_m is not active, or there was an error when flushing buffered
  97.      writes, or there was an error closing the underlying file descriptor.
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.